Back to Installation | Onward to Views

Remote Mail Configuration

Configuration of Remote Mail is accomplished through editing a text file named "Net.Dreams Remote Mail.cfg", which is located in your server's plug-in folder. Each configuration option is defined on its own line as "variablename: value". Lines begining with the pound sign (#) are ignored.

The easiest way to configure Remote Mail is to start with the configuration file included with the software distribution. All changes take effect the next time you launch your web server.

Options and their meanings

License-Key
When you purchase Remote Mail, you receive a license key, which is a sequence of numbers and letters. Adding your license key to your configuration file will remove the runtime restrictions on the software.
Default-Servername
If a user does not specify which POP server they wish to connect to, this is the server that will be used.
Allow-Foreign-Servers
Set to "true" or "on" to allow users to specify the forign POP server to which they wish to connect. Set to "false" or "off" to restrict all users to the POP server specified in Default-Servername
Session-Timeout
This is the number of seconds that a session may be idle before it is deleted. See the heading "Sessions" below for more information.
Pop-Connection-Refresh
This is the number of seconds to wait between "NOOP" commands. Remote Mail sends these commands to a POP server to keep a POP connection alive.
Default-Mailbox-Length
This is the number of messages displayed in a mailbox.
Max-Message-Size
This is the maximum message size allowed to read, in Kilobytes. See the section on "Memory Useage" below for more information.
PIXO-Preprocessor
Requests that all views be processed by another plug-in before Remote Mail interprets them.
Enable-APOP
If set to "on", this instructs Remote Mail to use the "APOP" method for logging on to mail servers when possible. APOP is more secure than the traditional username/password technique, because it encrypts the password before sending it to the mail server. If your mail server supports APOP, you should try turning on this setting.
Default-Charset
Determines the character set used for most Views. The only exception is the Message view, where the character set is determined by the message being displayed. The default is "US-ASCII".
Default-Page-Expiration
Causing pages to expire prevents the unauthorized use of the "Back" button in many browsers. Once a page has expired, using the back button will re-load the page. If the session that generated the page is no longer valid, this causes the login screen to be displayed. The value is measured in seconds.

Sessions

When a user first logs in to their mailbox via Remote Mail, a session is established for them. Remote Mail establishes a connection to the user's POP account and sets up storage space for mail headers and messages. When the user views the mailbox listing, Remote Mail retrieves and stores the headers. When the user wants to read a message, Remote Mail retrieves and stores the desired message. When the user deletes a message, Remote Mail marks the message for deletion. Finally, when the session terminates Remote Mail sends delete commands for all the messages the user wanted to delete, closes the POP connection and releases all memory used by that session.

A session can be terminated for different reasons. If a user hasn't issued any commands for a while (like viewing the mailbox, composing a message, etc) then the session is said to have "timed out" and is terminated. The length of inactivity allowed is governed by the "Session-Timeout" configuration in the "Net.Dreams Remote Mail.cfg" file. If a user clicks on the "logout.remotemail" link, or the [logout] parameter is discovered in any request, then the user's session is immediately terminated. This is the preferred way for users to end their sessions.

During a session, the user is identified by an HTTP "cookie". The cookie name is "sid" and its value is a long random string of characters. This cookie is what links a particular browser to a specific session inside Remote Mail. When a session is terminated because a user logs out, the browser is notified that it's cookie has expired. Any attempt to use a bad or expired cookie causes the login screen to be displayed.

Memory Useage

Because Remote Mail does all of it's work in RAM, there must be a limit to the maximum message size allowed. Imagine, if you will, one hundred users each viewing messages that are 200K long. You would need 20Megs of RAM just to accomodate this! While many servers have this kind of memory, not everyone does.

Each session can have up to 5 messages in memory. The theory is that users may wish to re-read a message they read only a few minutes ago, so it is cached in RAM. As the user reads more messages, the older messages are released from memory. Each session can take up to (5 * Max-Message-Size) Kilobytes of RAM. Keep in mind that most messages are quite small, so only an occasional message will be larger than about 20K.

A future version of Remote Mail will write all large session data (such as attachments) to disk. This will slightly degrade performance, but remove the message size restrictions.

More Net.Dreams Software